Allow user to control binding categories in a more fine-grained manner.

In particular, we will be able to include/exclude complete binding categories,
as well as rename declarations in term-level categories (e.g., functions,
function pointers, or globals).

We will have

data TermCategory =
    -- | Foreign import bindings with a @safe@ foreign import modifier.
    CSafe
    -- | Foreign import bindings with an @unsafe@ foreign import modifier.
  | CUnsafe
    -- | Pointers to functions; generally @unsafe@.
  | CFunPtr
    -- | Temporary category for bindings to global variables or constants.
  | CGlobal

data Category =
    -- | Types (top-level bindings).
    CType
  | CTerm TermCategory

-- | A category may contain types or terms.
type data CategoryLvl = LvlType | LvlTerm

-- | Include or exclude categories.
--
-- Possibly rename declarations in categories of 'Level' 'LvlTerm'. We only
-- allow renaming of 'LvlTerm' because for 'LvlType' we would also need to
-- rename the use sites, instances etc.
type Choice :: CategoryLvl -> Star
data Choice lvl where
  ExcludeCategory     :: Choice lvl
  IncludeTypeCategory :: Choice LvlType
  IncludeTermCategory :: RenameTerm -> Choice LvlTerm

Defaults

• TH and literate modes: useSafeCategory.
• preprocess mode: use all categories.

Remarks

• Followup task: Command line configuration, see Command line options for specifying (ByCategory ByCategory.Choice) in the preprocessor #1328

Tasks

After meeting with Edsko:

• We need to ensure that we do not rename unique symbols; we need some other changes before we can do so, and will pause this PR until then.

• We want to extend the scope of the golden tests to check that we do not rename definition sites that have use sites.

• The rename function needs to be discussed.

• Fix Function pointer bindings should not have _ptr suffix #1262

• Golden test case for Function pointer bindings should not have _ptr suffix #1262 <- We want to test the category choice renaming feature!

• Check that empty modules are not created (@jorisdral ?) -> I think we should check this in a basic integration test (included in this PR), but handle the fixtures in a seprate task/PR.